/*
 * Copyright (C) 2010 Fred Barrie This program is free software: you can
 * redistribute it and/or modify it under the terms of the GNU General Public
 * License as published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version. This program is distributed
 * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU General Public License for more details. You should have received
 * a copy of the GNU General Public License along with this program. If not, see
 * <http://www.gnu.org/licenses/>.
 */
package org.aergia.vinny.database;

import java.util.Collection;

import javax.jws.WebService;

import org.aergia.vinny.database.pojo.Card;
import org.aergia.vinny.database.pojo.Location;
import org.aergia.vinny.database.pojo.OperatingHours;
import org.aergia.vinny.database.pojo.Organization;
import org.aergia.vinny.database.pojo.Scan;
import org.aergia.vinny.database.pojo.Service;
import org.aergia.vinny.database.pojo.ServiceType;
import org.aergia.vinny.database.pojo.Skill;
import org.aergia.vinny.database.pojo.SkillRate;
import org.aergia.vinny.database.pojo.VinnyOption;
import org.aergia.vinny.database.pojo.VinnyRole;
import org.aergia.vinny.database.pojo.VinnyUser;
import org.aergia.vinny.database.pojo.Volunteer;
import org.aergia.vinny.database.pojo.VolunteerGroup;
import org.aergia.vinny.database.pojo.Workstation;

/**
 * @author fred
 */
@WebService(portName = "DatabaseServicePort", serviceName = "DatabaseService", targetNamespace = "http://aergia.org/wsdls/vinny_1", name = "DatabaseService")
public interface DatabaseService {

	/**
	 * Add a new <code>Card</code> into the system. A card uniquely identifies a
	 * volunteer. A volunteer may have multiple cards over her lifetime but only
	 * one card is active at a time per volunteer.
	 * 
	 * @param card
	 *            - the card to be added.
	 * @return the persistence ID of the card or -1 for an error.
	 */
	int addCard(Card card);

	/**
	 * Add a new <code>VolunteerGroup</code> into the system. A volunteer group
	 * is a way to group volunteers for reporting purposes.
	 * 
	 * @param group
	 *            - the group to be added.
	 * @return the persistence ID of the group or -1 for an error
	 */
	int addGroup(VolunteerGroup group);

	/**
	 * Add a new <code>Location</code> into the system. A location is where the
	 * vinny software runs at.
	 * 
	 * @param location
	 *            - the location to be added.
	 * @return the persistence ID of the location or -1 for an error
	 */
	int addLocation(Location location);

	/**
	 * Add a new set of
	 * <code>OperatingHours<code> into the system. An operating hours object represents the start and stop times for a location on a particular day of the week.
	 * 
	 * @param operatingHours
	 *            - hours for one day of the week to be added.
	 * @return the persistence ID of the operating hours or -1 for an error
	 */
	int addOperatingHours(OperatingHours operatingHours);

	/**
	 * Add a new <code>VinnyOption</code> into the system. An option controls
	 * how the vinny systems works.
	 * 
	 * @param option
	 *            - the option to be added.
	 * @return the persistence ID of the option or -1 for an error
	 */
	int addOption(VinnyOption option);

	/**
	 * Add a new
	 * <code>Organization<code> into the system.  An organization is the top level reporting structure.
	 * 
	 * @param organization
	 *            - the organization to be added.
	 * @return the persistence ID of the organization or -1 for an error
	 */
	int addOrganization(Organization organization);

	/**
	 * Add a new
	 * <code>Role<code> into the system. A role defines what functions a user can perform on the system.
	 * 
	 * @param role
	 *            - the role to be added.
	 * @return the persistence ID of the role or -1 for an error
	 */
	int addRole(VinnyRole role);

	/**
	 * Add a new <code>Scan</code> record to the database. A scan is the
	 * recording of a volunteer's card at a certain location at a give time.
	 * 
	 * @param scan
	 *            - the scan to be added.
	 * @return the persistence ID of the scan or -1 for an error
	 */
	int addScan(Scan scan);

	/**
	 * Add a new <code>Service</code> record to the database. A service is the
	 * amount of time that a volunteer spent at a location.
	 * 
	 * @param service
	 *            - the service to be added.
	 * @return the persistence ID of the service or -1 for an error.
	 */
	int addService(Service service);

	/**
	 * Add a new <code>Service Type</code> record to the database. A service
	 * type is what type of service the volunteer while volunteering.
	 * 
	 * @param serviceType
	 *            - the serviceType to be added.
	 * @return the persistence ID of the service type or -1 for an error.
	 */
	int addServiceType(ServiceType serviceType);

	/**
	 * Add a new <code>Skill</code> record to the database. Volunteers may have
	 * different skills that can be accounted for a different rates.
	 * 
	 * @param skill
	 *            - the skill to be added.
	 * @return the persistence ID of the skill or -1 for an error.
	 */
	int addSkill(Skill skill);

	/**
	 * Add a new <code>SkillRate</code> record to the database. The rate that
	 * the location values the skilled volunteer.
	 * 
	 * @param skillRate
	 *            - the skill rate to be added.
	 * @return the persistence ID of the skillRate or -1 for an error.
	 */
	int addSkillRate(SkillRate skillRate);

	/**
	 * Add a new <code>VinnyUser</code> record to the database. A user of the
	 * vinny software.
	 * 
	 * @param user
	 *            - the user to be added.
	 * @return the persistence ID of the user or -1 for an error.
	 */
	int addUser(VinnyUser user);

	/**
	 * Add a new <code>Volunteer</code> record to the database. A volunteer
	 * who's time is recorded in the vinny system.
	 * 
	 * @param volunteer
	 *            - the volunteer to be added.
	 * @return the persistence ID of the volunteer or -1 for an error.
	 */
	int addVolunteer(Volunteer volunteer);

	/**
	 * Add a new <code>Workstation</code> record to the database. A workstation
	 * is place where a volunteer's card is scanned.
	 * 
	 * @param workstation
	 *            - the workstation to be added.
	 * @return the persistence ID fo the workstation or -1 for an error.
	 */
	int addWorkstation(Workstation workstation);

	/**
	 * Get the <code>Card</code> for this card number.
	 * 
	 * @param cardNumber
	 * @return the Card for the specified card number or NULL
	 */
	Card getCard(String cardNumber);

	/**
	 * Get the list of cards.
	 * 
	 * @return a list of cards, it maybe empty
	 */
	Collection<Card> getCards();

	/**
	 * Get a list of volunteer groups for this location.
	 * 
	 * @param locationId
	 *            - ID of the location
	 * @return the defined groups, it maybe empty
	 */
	Collection<VolunteerGroup> getGroups(int locationId);

	/**
	 * Get the <code>Location</code> for the specified location.
	 * 
	 * @param locationId
	 *            - persistence ID of the location to be returned.
	 * @return the Location for the specified ID or NULL
	 */
	Location getLocation(int locationId);

	/**
	 * Get the list of locations.
	 * 
	 * @return the list of locations, it maybe empty
	 */
	Collection<Location> getLocations();

	/**
	 * Get the list of <code>OperatingHours</code> for the specified location.
	 * 
	 * @param location
	 *            - the ID of the location.
	 * @return the list of operating hours, it maybe empty
	 */
	Collection<OperatingHours> getOperatingHours(int locationId);

	/**
	 * Get a list of options for a location
	 * 
	 * @param locationId
	 *            - the ID of the location.
	 * @return the list of options for the location, it maybe empty
	 */
	Collection<VinnyOption> getOptions(int locationId);

	/**
	 * Get a list of all organizations.
	 * 
	 * @return a list of organizations, it maybe empty
	 */
	Collection<Organization> getOrganizations();

	/**
	 * A list of defined roles.
	 * 
	 * @return a list of roles.
	 */
	Collection<VinnyRole> getRoles();

	/**
	 * A list of scans at the specified location.
	 * 
	 * @param locationId
	 *            - the ID of the location
	 * @return list of scans, it maybe empty
	 */
	Collection<Scan> getScans(int locationId);

	/**
	 * A list of services at the specified location.
	 * 
	 * @param locationId
	 *            - the ID of the location.
	 * @return a list of services at the location, it maybe empty
	 */
	Collection<Service> getServices(int locationId);

	/**
	 * A list of services types at the specified location.
	 * 
	 * @param locationId
	 *            - the ID of the location
	 * @return list of all service types at the location, it maybe empty
	 */
	Collection<ServiceType> getServiceTypes(int locationId);

	/**
	 * A list of skill rate at the specified location.
	 * 
	 * @param location
	 *            - the ID of the location.
	 * @return list of skill rates at the location, it maybe empty.
	 */
	Collection<SkillRate> getSkillRates(int locationId);

	/**
	 * A list of skills at a location.
	 * 
	 * @param location
	 *            - the ID of the location.
	 * @return list of skills at the location, it maybe empty.
	 */
	Collection<Skill> getSkills(int locationId);

	/**
	 * Return all un-approved services at a location. An un-approved service is
	 * defined as an active service that has not been approved.
	 * 
	 * @param locationId
	 *            - the ID of the location.
	 * @return un-approved scans can be empty
	 */
	Collection<Service> getUnapprovedServices(int locationId);

	/**
	 * Return all unmatched scans at a location. An unmatched scan is defined as
	 * an active scan that has no associated service.
	 * 
	 * @param - the ID of the location.
	 * @return unmatched scans can be empty
	 */
	Collection<Scan> getUnmatchedScans(int locationId);

	/**
	 * Return all users at a location.
	 * 
	 * @param locationId
	 *            - the ID of the location.
	 * @return list of all users at a location, it maybe empty
	 */
	Collection<VinnyUser> getUsers(int locationId);

	/**
	 * Get the Volunteer with this volunteer ID.
	 * 
	 * @param volunteerId
	 *            - the ID of the volunteer
	 * @return the Volunteer with this volunteer ID or NULL.
	 */
	Volunteer getVolunteer(int volunteerId);

	/**
	 * List of all volunteers.
	 * 
	 * @return collection of volunteers can be empty
	 */
	Collection<Volunteer> getVolunteers();

	/**
	 * List of all workstations at a location.
	 * 
	 * @return list of all workstations at a location, it maybe empty
	 */
	Collection<Workstation> getWorkstations(int locationId);

	/**
	 * Save the card to the database.
	 * 
	 * @param card
	 * @return the result of saving the card.
	 */
	boolean saveCard(Card card);

	/**
	 * Save the group to the database.
	 * 
	 * @param group
	 * @return the result of saving the group
	 */
	boolean saveGroup(VolunteerGroup group);

	/**
	 * Save the operating hours to the database.
	 * 
	 * @param hours
	 * @return the result of saving the operating hours
	 */
	boolean saveOperatingHours(OperatingHours hours);

	/**
	 * Save the option to the database.
	 * 
	 * @param option
	 * @return the result of saving the option.
	 */
	boolean saveOption(VinnyOption option);

	/**
	 * Save the organization to the database.
	 * 
	 * @param organization
	 *            - the organization to save.
	 * @return the result of saving the organization.
	 */
	boolean saveOrganization(Organization organization);

	/**
	 * Save the role to the database.
	 * 
	 * @param role
	 * @return the result of saving the role
	 */
	boolean saveRole(VinnyRole role);

	/**
	 * Save the scan to the database.
	 * 
	 * @param scan
	 * @return the result of saving the scan.
	 */
	boolean saveScan(Scan scan);

	/**
	 * Save the service to the database.
	 * 
	 * @param service
	 * @return the result of saving the service.
	 */
	boolean saveService(Service service);

	/**
	 * Save the service type to the database.
	 * 
	 * @param serviceType
	 * @return the result of saving the serviceType
	 */
	boolean saveServiceType(ServiceType serviceType);

	/**
	 * Save the skill to the database.
	 * 
	 * @param skill
	 *            - the skill to be saved.
	 * @return the result of saving the skill
	 */
	boolean saveSkill(Skill skill);

	/**
	 * Save the skill rate to the database.
	 * 
	 * @param skillRate
	 * @return the result of saving the skill rate
	 */
	boolean saveSkillRate(SkillRate skillRate);

	/**
	 * Save the user to the database.
	 * 
	 * @param saveUser
	 * @return the result of saving the user.
	 */
	boolean saveUser(VinnyUser saveUser);

	/**
	 * Save the volunteer to the database.
	 * 
	 * @param volunteer
	 * @return the result of saving the volunteer.
	 */
	boolean saveVolunteer(Volunteer volunteer);

	/**
	 * Save the workstation to the database.
	 * 
	 * @param workstation
	 * @return the result of saving the workstation
	 */
	boolean saveWorkstation(Workstation workstation);

}
